Reference List Menu Library -turn page- Reference List Dialog Library

Contents | Start

The Dialog Library

3. The Dialog Library
3.1 3.2 3.3 3.4 3.5	Structure of a Dialog Box Definition of a Dialog Box Calling a Dialog Box Evaluation of a Dialog Box Sample Program for Dialog Boxes
Reference List Dialog Library

This section of the EasyGem Library now deals with the dialog boxes, these little windows that appear on the screen whenever the user is supposed to select or type in something or when the progress of a function (e.g., printing a document) is being reported. The user can comfortably choose between various alternatives using a variety of buttons or input small sections of text.

3.1 Structure of a Dialog Box Let's start with some practical exercises. We just want to display a small dialog box on the screen. First, we need to initialize EasyGem (using Easy_Init). Then the main program follows. In order to be able to work with dialog boxes, we have to define the appearance of the box first. This is done as simply and easily using EasyGem as it is to work with and define menus. Just use the appropriate command to define your dialog box in the program. When using EasyGem, a dialog box is divided into lines in which you can place the following elements: Titles: These will be displayed centered in their own box. Texts: Well, just some normal text. Buttons: The mouse can be used to click on buttons. They will then appear inverted and are thus selected. If an already selected button is clicked on again, the button will be deselected and appears normal. Radio Buttons: You might still be familiar with the buttons that were used to select the frequency bands on older radios (ultra-short-wave, medium-wave, short-wave, etc.). When one was pushed, all others jumped up. Only one button at a time was depressed. Today's software radio buttons were named after these old radio buttons. Only one button is selected at any one time. If a user clicks on another button, only this other button will be selected. One can recognize radio buttons by their little circles located in front of the text, which, in case of a selection, will be filled. Checkboxes: These are small little squares next to a text. If the mouse is used to click on the square, a little check mark or cross will appear inside of the box. This means that this particular item is then activated or selected. Exit Buttons: They correspond to normal buttons but when clicked on, exit the dialog box. Consequently, each dialog box has to contain at least one, otherwise one could not exit the box. Input: Here, the user can input text. Output: Texts that are only known after the dialog box has been defined can be displayed here. These are the elements you can use to create or define your dialog box.

3.2 Definition of a Dialog Box Any defining process always starts with the command Make_Dialog and always ends with End_Dialog. The actual definition, determining the appearance of the box, is located between these two commands:

Make_Dialog Type

Start definition.

Make_Dialog Box$,Dialog_Id[,Name$]

The second variation of this command using 2 or 3 parameters was implemented only for reasons of compatibility with older EasyGem versions. The parameters no longer have any significance. It is best, therefore, if you use only the first variation. In Type, you can here pass the numbers 0 or 1. Type=0 generates a modal, non-adjustable dialog box. Type=1 generates a modal dialog box as well but one that is equipped with a moving bar. You can also switch to other programs while this dialog box is open as well as move the dialog box around the screen. However, you cannot continue working with your program until the dialog box has been closed. The actual definition - explained below - follows after Make_Dialog. The following constitutes the conclusion :

End_Dialog [Box$,]R Dialog_Id

Conclude definition.

Box$ has no significance and serves only for the compatibility with older EasyGem versions and can be omitted at all times. You will receive an identification number in Dialog_Id, same as with End_Menu, which you have to indicate any time the dialog box is accessed. If an error should occur during the definition process, then Dialog_Id=0.

Example:

Make_Dialog 1  'The definition of the dialog box is listed here. End_Dialog Dialog1

Clear_Dialog [Box$,] Dialog_Id

Delete dialog box.

This command deletes the dialog box with the identification number indicated in Dialog_Id. Again, the term Box$ is possible only for reasons of compatibility and has no significance. You actually need this command only when no other identification numbers are available any more.

Now we are reaching the actual definition phase. Let's start with the titles:

D_Title [Line_No,]Txt$

Define a title bar in the dialog box.

A title will be displayed centered in a small box by itself. Line_No indicates the line within the dialog box in which the title is supposed to appear (1=at very top, 2=one text line lower, etc.). Txt$ is the text that is supposed to be displayed as the title. Txt$ will be written in the title bar of the dialog box if Lino_No=0 or if this parameter is omitted. Of course, this functions only if the dialog box is equipped with a title bar (moving bar), which means you have to indicate Type=1 in Make_Dialog.

Example:

Make_Dialog 0  D_Title 2,"Title" End_Dialog Dialog1

This definition fixes the appearance of the dialog box. However, the dialog box does not appear on the screen yet! You can see that the line number for D_Title in our example is set to 2 . This means that the dialog box, which always starts with line 1, has one empty line above the title.

D_Text Line_No,Txt$

Define a text line in the dialog box.

This call will generate a text line in your dialog box. Line_No is once again that line within the dialog box, in which the text is supposed to appear. Txt$ represents the text itself.

D_Button Line_No,Txt$

Define normal button.

D_Radiobutton Line_No,Txt$

Define radio button.

D_Checkbox Line_No,Txt$

Define checkbox.

D_Exitbutton Line_No,Txt$[,Defaultbutton]

Define exit button.

You can define all four different types of buttons using this command. Line_No always indicates the line within the dialog box in which the respective button(s) are supposed to appear. Txt$ contains information about any other buttons or text, which are also supposed to be present in the line. Defaultbutton is a parameter that may be used to determine which exit button may also be triggered simply by pressing the Return/Enter key. This button will then be displayed with a thick border. Each dialog box has to offer an opportunity to leave it again. Such an exit option can only be provided via the exit buttons. Each dialog box, therefore, has to have at least one such exit button, otherwise EasyGem will report an error and returns a zero in Dialog_Id. The structure of Txt$ is not quite as simple. An example will best serve to illustrate the use and application of Txt$:

D_Radiobutton 4, "Correct?[Yes][No][Perhaps]"

This line defines three radio buttons in the 4th line of the dialog box with the contents [Yes], [No] and [Perhaps], preceded by the text "Correct?":

Correct?	[Yes]	[No]	[Perhaps]
normal text	1. button	2. button	3. button

This means that a line with buttons may also contain text. Everything located inside of a [square bracket] is a button, everything else is text. Text may also be located in between the square brackets. If you want to use the parameter Defaultbutton with D_Exitbutton, which would select one exit button out of many to be selectable by pressing [Return], you have to pass the so-called object number of this button in the procedure D_Exitbutton. The object number may be obtained by simply counting the individual pieces of text and the buttons. Object number 1 in the sample line containing D_Radiobutton is therefore not the button [Yes], but the text "Correct?"! The button [Yes] is object number 2, [No]is object number 3, etc. If there should be blank spaces between the buttons, e.g., in order to increase the distance between the buttons, these do count as text once again and therefore have their own object numbers, which you may not omit when counting! Example: We will define a line with the exit buttons [Delete] and [Cancel], whereby [Cancel] is supposed to be the default button.

D_Exitbutton 7,"Do you wish to: [Delete] or [Cancel] ?",4

The button [Cancel] is here object number 4! The text "Do you wish to: " is object number 1, object 2 is represented by the button [Delete], object 3 is the text " or ", object 4 is the button [Cancel], and object 5 is represented by the text " ?".

D_Empty Line_No

Define an empty line in dialog box.

This procedure defines an empty text line. Actually, this line only makes sense at the end of the dialog box, namely for lengthening or extending the size of the box so that the Exit_Button does not look as if precariously teetering on the edge.

D_Input Line_No,Txt$,Input_Len[,Flag]

Define an input line.

Line_No indicates once more in which line of the dialog box the input is supposed to start. Txt$ contains the text to be displayed to the left of the actual input. Input_Len indicates the maximum length - in characters - of the expression to be inserted. Flag has no significance any longer and thus may be omitted.

Example:

D_Input 7,"Indicate your printer model: ",6

This line will define an input field in line 7 of the dialog box, which may contain maximally 6 characters.

D_Output Line_No,Txt$,Output_Len

Define an output line.

Once again, Line_No indicates the line in which text is supposed to be output. As in the case of D_Input,Txt$ is permanently written into the line. Output_Len indicates the length of the text, which may be displayed in addition. This text may be changed during the execution of the program.

3.3 Calling a Dialog Box Now we have familiarized ourselves with all commands concerning the definition of a dialog box and can now define any dialog box we desire. The following procedure is needed to display a dialog box on the screen:

Easy_Dialog Dialog_Id

Easy_Dialog Box$,Dialog_Id[,R Object_No[,R Line_No]]

Display the dialog box.

Easy_Dialog Dialog_Id,X,Y,R Object_No,R Line_No

Box$ has no significance and is again only included because of compatibility reasons. As we know, Dialog_Id is the identification number, which has been returned to you after End_Dialog. Object_No is the object number within that line in which the clicked on exit button is located. Line_No represents the line number in which the clicked on exit button is located. This information is needed only if there are several lines with exit buttons. X and Y may be used to determine where on the screen the dialog box is supposed to appear. X=0 and Y=0 generate a centered display. Only after the user has clicked on an exit button or pressed the key [Return], will the command Easy_Dialog return. A tip for the pros: The procedure Easy_Dialog actually consists out of the following sub-procedures, which may also be called individually, of course:

D_Show [Box$,]Dialog_Id

Display dialog box.

D_Show Dialog_Id,X,Y

Prohibits menu and window activities and displays the dialog box. You can determine where on the screen the dialog box is supposed to be displayed using X and Y. X=0 and Y=0 generate a centered display.

D_Redraw Dialog_Id[,Line_No]

Redraw dialog box.

Displays the dialog box. Only now it will become visible on screen. Use Line_No to determine that only this one line is redrawn.

D_Edit Dialog_Id[,R Object_No[,R Line_No]]

Display and edit dialog box.

D_Edit_ Dialog_Id[,R Object_No[,R Line_No]]

Edit dialog box.

Both of these procedures allow the user to input information into the dialog box. D_Redraw is first called in the case of the first procedure.

D_Event Dialog_Id,R Object_No[,R Line_No]

Evaluate an event.

This procedure functions similarly to D_Edit_, the only difference is that it will return immediately, even if an exit button has not been pressed yet. This has the result that you remain in control over the program's flow and execution; however, you also have to make sure that the dialog box disappears again from the screen at the indicated point in time. This is achieved with the following command:

D_Hide Dialog_Id

Remove dialog box from the screen.

Removes the dialog box from the screen and permits further menu and window activities. In order to control the dialog box from within the program with a higher level of detail, you may use this individual procedures. Were you to call only Easy_Dialog, the procedure would not return until an exit button has been selected. If, however, one would like to display the current progress of a specific task, e.g., when editing a file, one would initially display the dialog box using only D_Show and then apply D_Redraw to constantly update the box. After the task has been concluded, one could remove the box using D_Hide, or one first calls D_Edit_ to cause the user to click on [OK] or to trigger other activities. We will supply another example to clarify the procedure. Here, the date and time of day are supposed to be displayed within a dialog box. The time will be updated in intervals of one second.

Easy_Init 'Define dialog box. Make_Dialog  D_Title 1,"Date and Time"  D_Output 3,"Date ",12  D_Output 4,"Time ",12  D_Exitbutton 6," [Cancel]",2  D_Empty 7 End_Dialog Date_Time 'Initialize variables and dialog box. Tim=TIMER Dialog_Text$(3,Date_Time)=DATE$ Dialog_Text$(4,Date_Time)=TIME$ 'Display dialog box and update in loop. D_Show Date_Time:D_Redraw Date_Time REPEAT  IF TIMER >Tim+200 THEN   Dialog_Text$(4,Date_Time)=TIME$   D_Redraw Date_Time,4:'Update only line 4.   Tim=TIMER  ENDIF  'Check if [Cancel] has been pressed.  D_Event Date_Time,Object_No:  'Additional program code could be listed here. UNTIL Object_No D_Hide Date_Time:'Remove dialog box again. Easy_Exit END

Note: While the dialog box is visible on the screen, it is of course impossible to continue working in any other windows because we are dealing with a modal dialog box. However, your program is able to perform other activities in the background, e.g., calculations or the creation of a virtual screen, which will be displayed after the dialog box has been exited.

3.4 Evaluation of a Dialog Box The commands discussed up to this point are suitable for defining and displaying a dialog box on screen. It is, of course, essential to be able to detect which buttons have been clicked on, what text the user has written into the dialog box, etc. You will find out next how to achieve this task . We have already described with what type of exit button to leave the dialog box when we discussed Easy_Dialog. In order to make this possible for other buttons and texts as well, two global variable fields are used, which are utilized by EasyGem to store the desired information. Let's start with the buttons. The following variable field will be used for this task:

Dialog_Button%F(Line_No,Object_No,Dialog_Id)

Determine or set status of button.

You can see that this is a so-called flag field (%F). The field elements can consist of only two conditions: false=(0) or true=(-1). Zero (0) indicates for all buttons a "not selected" status (display on screen: normal), -1 represents "selected" (display on screen: inverted or checked off, respectively, etc.). Line_No indicates the line within the dialog box whose condition or status we want to ascertain, and Object_No is the number of the object within the line (objects are numbered same as described for D_Exitbutton). As you probably noticed, not only does every button have its assigned variable, but every text has one as well. This variable, however, is always zero for any text since a text cannot be selected by clicking on it.

Example:

Easy_Init Make_Dialog  D_Radiobutton 2,"Correct?[Yes][No][Perhaps]"  D_Exitbutton 4," [ OK ]",2  D_Empty 5 End_Dialog Dialog1 Easy_Dialog Dialog1 IF Dialog_Button%F(2,3,Dialog1) THEN  PRINT "No has been selected!" ENDIF PRINT "End program with any key." REPEAT UNTIL LEN(INKEY$) Easy_Exit END

You can therefore determine if a certain button has actually been clicked on by querying the content of the appropriate variable. This is also applicable in the reverse direction: If you set a button to "select" (unequal zero) before calling Easy_Dialog, this button is then already selected when calling the dialog box. We will provide you with a demo program a few paragraphs below, which illustrates the use of the field Dialog_Button%F for this specific purpose. In case of a line with radio buttons, of which only one can be selected at any one time, another functions exists, which returns the number of the button directly:

FN Rbutton(Line_No,Dialog_Id)

Determine number of pressed radio button.

Returns the object number of the selected button within a radio button line. Zero (0) is returned if no button is selected. This functions similarly for texts when using D_Input. The respective field will exhibit one parameter less, since only one text per line is possible:

Dialog_Text$(Line_No,Dialog_Id)

Determine or set text in line Line_No.

This can be used to initialize a text and to query the same text later - as shown in the demo program below. When using D_Output, everything appears like that. Nevertheless, it serves no real purpose to query the text again because it cannot be modified by the user anyhow. Incidentally, if you want to delete all the buttons and texts of any given dialog box, this task can also be performed via a specific command:

Clear_Parameter(Dialog_Id)

Clear all buttons and texts within a dialog box.

Naturally, Dialog_Id is once again the identification number of the dialog box.

3.5 Sample Program for Dialog Boxes

Easy_Init 'Define first dialog. Make_Dialog  D_Title 1," My first dialog box "  D_Text 3," This is my first dialog box. "  D_Radiobutton 4," Correct?[Yes][No][Perhaps] "  D_Exitbutton 6," [ OK ]",2  D_Empty 7 End_Dialog Dialog1 'Define second dialog box. Make_Dialog  D_Title 1, " My second dialog box "  D_Text 3," This is: "  D_Button 4," [Great][Super][Tops][Fantastic] "  D_Input 6," Make a comment: ",14  D_Exitbutton 8," [End] [Once more] ", 4  D_Empty 9 End_Dialog Dialog2 'Initialize dialog buttons. Dialog_Button%F(4,2,Dialog1)=-1 Dialog_Button%F(4,2,Dialog2)=-1 Dialog_Button%F(4,4,Dialog2)=-1 'Initialize dialog_text of the input line. Dialog_Text$(6,Dialog2)="Oh, how nice!" 'Call dialog boxes. REPEAT  Easy_Dialog Dialog1  Easy_Dialog "",Dialog2,Exit_Button_No UNTIL Exit_Button_No=2 Easy_Exit 'Report status of dialog boxes. PRINT "Dialog 1: "; SELECT FN Rbutton(4,Dialog1)  CASE 2:PRINT "Yes"  CASE 3:PRINT "No"  CASE 4:PRINT "Perhaps" END_SELECT PRINT "Dialog 2: "; IF Dialog_Button%F(4,2,Dialog2) THEN PRINT "Great" IF Dialog_Button%F(4,3,Dialog2) THEN PRINT "Super" IF Dialog_Button%F(4,4,Dialog2) THEN PRINT "Tops" IF Dialog_Button%F(4,5,Dialog2) THEN PRINT "Fantastic" PRINT "- ";Dialog_Text$(6,Dialog2) PRINT "End program with any key." REPEAT UNTIL LEN(INKEY$) END

Reference List Menu Library -turn page- Reference List Dialog Library

Contents | Start

© 1998-1999 Berkhan-Software www.berkhan.com | Home